refactor(spec,client,metadata-protocol,runtime)!: 退役 workflow 服务槽位与 graphql 残留 (#4451) - #4473
Merged
os-zhuang merged 5 commits intoAug 1, 2026
Merged
Conversation
… service slot and the stray graphql entry (#4451) The `workflow` slot was ADR-0078's silently-inert declaration at every layer at once, and had been since it was written: a `CoreServiceName` nothing ever registered or resolved, an `IWorkflowService` contract with zero implementations, a `WorkflowProtocol` whose three methods no code ever provided, an `ApiRoutes.workflow` field no builder could truthfully populate, and an `/api/v1/workflow` advertisement for a path no host ever mounted. The pre-#3586 `DEFAULT_DISPATCHER_ROUTES` already listed that path among "routes that never existed"; ADR-0115 Evidence 5 verified the slot itself across both repositories — "no code in this repository resolves either slot", the only touches being plugin-dev's since-retired stub probe and the generic discovery walk. Nothing here is being taken away from anyone, because the capability the slot promised has been live elsewhere for majors: record state machines are enforced by the `state_machine` validation rule (`StateMachineSchema` stays authorable on the object), approvals are first-class flow nodes on the approvals runtime (ADR-0019 folded the standalone approval process into Flow), and record-triggered automation is lifecycle hooks + `record_change` flows. That is why this is a removal rather than an enforcement: there is no feature to build, only a second name for three that exist. Removed with it: the `graphql` entry in `CORE_SERVICE_PROVIDER` and the `graphql: { route: '/graphql' }` discovery entry. `graphql` was never a `CoreServiceName` — so nothing could occupy the slot and the entry was unreachable — and it declared a path the dispatcher had already dropped as out of the product plan (#2462 follow-on). The provider guard only checks that every SLOT has an entry, never that every entry is a slot, which is how the stray sat unchallenged. Direct cut inside the 17.x rc window, per ADR-0115 D5. The retirement kit: a `workflow-service-slot-retired` SemanticMigration on the major-17 step carries the FROM -> TO into spec-changes.json, the generated upgrade guide and the `spec_changes` MCP tool. These are TS/API surfaces and discovery RESPONSE fields — never stored in stack metadata — so there is no load-path conversion and nothing for `os migrate meta` to rewrite. The 21 `authorable-surface.json` baseline lines and 7 `json-schema.manifest.json` entries are dropped deliberately in the same change, following the plugin-runtime precedent: a `retiredKey()` prescription earns its keep at a parse the author reaches, and nothing parses these shapes any more. `os explain workflow` is kept as a redirect topic rather than deleted, mirroring content/docs/automation/workflows.mdx. It had been teaching a shape the spec never had (`states[]` / `transitions[]` / `approvers`); it now names the three live mechanisms instead.
…e-queue-route-conflict-8fwmfc
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 5 package(s): 119 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
The docs-drift check on PR #4473 earned its keep: my symbol-shaped grep (`IWorkflowService`, `WorkflowProtocol`, `api/v1/workflow`) found three pages and missed four PROSE mentions that describe the same retired slot in words. - `api/plugin-endpoints.mdx` documented three `/workflow/*` routes under a "not yet mounted … return 404 today" caveat. The caveat was already the tell: routes that 404 for the whole life of the declaration are not "not yet", and the slot behind them is gone now. The section becomes a redirect naming the three live mechanisms. - `kernel/services-checklist.mdx` carried it in three more places — the legend's 36-method count (now 33), the `null`-provider explanation, and a full "6. workflow Service" section still describing the three methods as pending rather than removed. The remaining `workflow` hits in `content/docs` are the ordinary English word (approval workflow, build workflow, GitHub Actions workflows) and stay.
…e-queue-route-conflict-8fwmfc
os-zhuang
deleted the
claude/discovery-cache-queue-route-conflict-8fwmfc
branch
August 1, 2026 09:49
17 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #4451.
维护者判断:workflow 的能力"是 automation 还是 approval,应该都有了",确认是旧设计、无业务价值 → 在 v17 一并退役。#4451 提的两条残留在这个 PR 里一起清掉。
为什么是退役而不是补实现
workflow是 ADR-0078 那种"声明了、从未实现"的形态,而且是每一层同时如此:CoreServiceName 'workflow'—— 从没有任何东西注册或解析这个槽位。ADR-0115 Evidence 5 双仓核实过:"no code in this repository resolves either slot",唯一的触碰是 plugin-dev 那张已退役的 stub 表和通用 discovery 遍历;IWorkflowService(87 行契约)—— 零实现;WorkflowProtocol的三个方法 —— 没有任何代码提供;ApiRoutes.workflow—— 没有 builder 能如实填充;/api/v1/workflow—— 没有任何 host 挂载过。Retire DEFAULT_DISPATCHER_ROUTES and the stalegraphqlentry in ApiRoutesSchema (spec-major) — #3563 follow-up #3586 删掉的DEFAULT_DISPATCHER_ROUTES注释里就写着它属于 "routes that never existed"。这不是从谁手上拿走东西 —— 它承诺的能力早就活在别处,而且已经好几个 major 了:
state_machine验证规则(StateMachineSchema仍然可授权在 object 上)record_changeflow(service-automation)所以这里没有"要先建的功能",只有三个已存在机制的第四个名字。ADR-0115 D5 授权在 17.x rc 窗口内直接切,不设弃用期。
一并清掉的 graphql 残留
graphql根本不是CoreServiceName—— 没有东西能占据这个槽位,条目本身不可达 —— 但它声明了一条 dispatcher 早已作为"不在产品计划内"删除的路径(http-dispatcher.ts:// /graphql removed — GraphQL is not in the product plan,#2462 follow-on)。它能一直没人管,是因为 provider 守卫只校验"每个槽位都有条目",从不校验"每个条目都是槽位"。退役套件
按
.claude/skills/spec-property-retirement走完:workflow-service-slot-retiredSemanticMigration 挂在 major-17 步骤上,FROM → TO 进入spec-changes.json、生成的 upgrade guide 和spec_changesMCP 工具;os migrate meta无事可做;authorable-surface.json+ 7 个json-schema.manifest.json条目刻意删除,遵循 plugin-runtime 先例 ——retiredKey()的价值在于让作者在能到达的 parse 上收到处方,而这些形态已经没有任何东西再 parse,处方无人可收即是噪音;major,runtime/metadata-protocolminor,携带完整 FROM → TO 与一行修复;Dead spec clusters removed表 + 升级清单、services-checklist(从 "Still open" 移除并说明去向)、http-protocol示例(顺带修掉示例里同样虚构的graphql路由)。os explain workflow保留为 redirect 条目而非删除,与content/docs/automation/workflows.mdx的处理一致 —— 它原本在教一个 spec 里从来不存在的形态(states[]/transitions[]/approvers),现在改为指向三个真实机制。被 gate 抓住三次,都走了正路
json-schema.manifest.json绊线 —— 7 个 schema "disappeared";authorable-surface.json21 个 key vanish —— 按 §2 的第三条路线(没人 parse ⇒ 删基线并在 changeset 里说明);'workflow'读成了枚举成员 —— 它的解析器抓CoreServiceName块内所有单引号 token,注释也算。改用反引号并在原地留了注记,免得下一个人重踩。全仓
pnpm build的 tsc 清扫是主要的消费者扫雷手段(退役套件 §1 的做法),它找出了StateMachineSchema变成未使用 import 这类 grep 抓不到的点。验证
pnpm test132/132 全绿(合并origin/main@ cdf4d9a 后重跑,含 feat(spec,service-datasource): datasource.config 按驱动契约校验 (#4410) #4465 的 driver config registry 与 kind:'react' 页面上 record:* 四个 block 全部失效——契约 publish 的 objectName/recordId 渲染器根本不读（#4340 后续） #4413)pnpm typecheck、check:i18n、provider 守卫全部通过check:generated八项产物同步plugin-hono-server失败,定位为并行跑 CLI 测试造成的资源竞争 —— 单独重跑 135/135 全绿,干净条件下的全量也全绿关联:#4451、#4318(PR #4448)、ADR-0115 Evidence 5 / D5、ADR-0019、ADR-0049、ADR-0078、#3586、#2462。
Generated by Claude Code